Available Intrinsic Functions

States.Format

This Intrinsic Function takes one or more arguments. The Value of the first MUST be a string, which MAY include zero or more instances of the character sequence {}. There MUST be as many remaining arguments in the Intrinsic Function as there are occurrences of {}. The interpreter returns the first-argument string with each {} replaced by the Value of the positionally-corresponding argument in the Intrinsic Function.

If necessary, the { and } characters can be escaped respectively as \\{ and \\}.

If the argument is a Path, applying it to the input MUST yield a value that is a string, a boolean, a number, or null. In each case, the Value is the natural string representation; string values are not accompanied by enclosing " characters. The Value MUST NOT be a JSON array or object.

For example, given the following Payload Template:

{
  "Parameters": {
    "foo.$": "States.Format('Your name is {}, we are in the year {}', $.name, 2020)"
  }
}

Suppose the input to the Payload Template is as follows:

{
  "name": "Foo",
  "zebra": "stripe"
}

After processing the Payload Template, the new payload becomes:

{
  "foo": "Your name is Foo, we are in the year 2020"
}

States.StringToJson

This Intrinsic Function takes a single argument whose Value MUST be a string. The interpreter applies a JSON parser to the Value and returns its parsed JSON form.

For example, given the following Payload Template:

{
  "Parameters": {
    "foo.$": "States.StringToJson($.someString)"
  }
}

Suppose the input to the Payload Template is as follows:

{
  "someString": "{\"number\": 20}",
  "zebra": "stripe"
}

After processing the Payload Template, the new payload becomes:

{
  "foo": {
    "number": 20
  }
}

States.StringsEqual

This Intrinsic Function takes a two string arguments and returns true if they are equal.

For example, given the following Payload Template:

{
  "Parameters": {
    "foo.$": "States.StringsEqual($.someString1, $.someString2)"
  }
}

Suppose the input to the Payload Template is as follows:

{
  "someString1": "ABC",
  "someString2": "DEF"
}

After processing the Payload Template, the new payload becomes:

{
  "foo": false
}

States.JsonToString

This Intrinsic Function takes a single argument which MUST be a Path. The interpreter returns a string which is a JSON text representing the data identified by the Path.

For example, given the following Payload Template:

{
  "Parameters": {
    "foo.$": "States.JsonToString($.someJson)"
  }
}

Suppose the input to the Payload Template is as follows:

{
  "someJson": {
    "name": "Foo",
    "year": 2020
  },
  "zebra": "stripe"
}

After processing the Payload Template, the new payload becomes:

{
  "foo": "{\"name\":\"Foo\",\"year\":2020}"
}

States.Array

This Intrinsic Function takes zero or more arguments. The interpreter returns a JSON array containing the Values of the arguments, in the order provided.

For example, given the following Payload Template:

{
  "Parameters": {
    "foo.$": "States.Array('Foo', 2020, $.someJson, null)"
  }
}

Suppose the input to the Payload Template is as follows:

{
  "someJson": {
    "random": "abcdefg"
  },
  "zebra": "stripe"
}

After processing the Payload Template, the new payload becomes:

{
  "foo": [
    "Foo",
    2020,
    {
      "random": "abcdefg"
    },
    null
  ]
}

States.ArrayGetItem

This Intrinsic Function takes two arguments. The first argument MUST be a Path. The second argument MUST be a number. The interpreter will return the Value of the item in the array identified by the Path at the index specified by the second argument.

For example, given the following Context and Payload Template:

{
  "Parameters": {
    "foo.$": "States.ArrayGetItem($.someArray, 1)"
  }
}

Suppose the input to the Payload Template is as follows:

{
  "someArray": ["dog", "cat", "bird"],
}

After processing the Payload Template, the new payload becomes:

{
  "someArray": ["dog", "cat", "bird"],
  "foo": "cat"
}

States.ArrayLength

This Intrinsic Function takes a single argument. The argument MUST be a Path. The interpreter will return the length of the array identified by the Path.

For example, given the following Context and Payload Template:

{
  "Parameters": {
    "foo.$": "States.ArrayLength($.someArray)"
  }
}

Suppose the input to the Payload Template is as follows:

{
  "someArray": ["dog", "cat", "bird"],
}

After processing the Payload Template, the new payload becomes:

{
  "someArray": ["dog", "cat", "bird"],
  "foo": 3
}

States.AppendToArray

This Intrinsic Function is used to append a value to an array. It requires two arguments: the first being the array of values, and the second being the value to append. The result is a new array with the value appended.

For example, given the following Context and Payload Template:

{
  "Values.$": "States.Array('element1', 'element2')",
  "MyValue": "element3"
}

{
  "Type": "Pass",
  "Parameters": {
    "Result.$": "States.AppendToArray($.Values, $.MyValue)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "Result": ["element1", "element2", "element3"]
}

States.ArraySplice

This Intrinsic Function takes four or more arguments. The first argument MUST be a Path. The second argument MUST be a number, representing the start index at which to begin changing the array. The third argument MUST be a number, indicating the number of elements to skip from the array starting at the start index. Subsequent arguments (if any) MAY be any value and will be inserted into the new array starting at the start index, replacing the removed elements.

This operation returns a new array with the specified changes applied. The original array referenced by the Path is not modified. For more information on the splice function, see MDN Web Docs.

For example, given the following Context and Payload Template:

{
  "Parameters": {
    "newArray.$": "States.ArraySplice($.originalArray, 1, 2, 'horse', 'donkey')"
  }
}

Suppose the input to the Payload Template is as follows:

{
  "originalArray": ["dog", "cat", "bird"],
}

After processing the Payload Template, the new payload becomes:

{
  "originalArray": ["dog", "cat", "bird"],
  "newArray": ["dog", "horse", "donkey"]
}

States.HexToDecimal

This Intrinsic Function takes a single argument whose Value MUST be a string containing only valid hexadecimal characters. The interpreter will convert this string to a decimal number.

For example, given the following Payload Template:

{
  "Parameters": {
    "SomeNumber.$": "States.HexToDecimal('1F0025')"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "SomeNumber": 2031653
}

States.DecimalToHex

This Intrinsic Function takes a single argument whose Value MUST be a number. The interpreter will convert this number to a string containing the hexadecimal representation of the number.

For example, given the following Payload Template:

{
  "Parameters": {
    "SomeHex.$": "States.DecimalToHex(2031653)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "SomeHex": "1F0025"
}

States.HexToByteCount

This Intrinsic Function takes three arguments. The first argument's value MUST be a string. The second argument MAY be a boolean indicating whether the output should be returned as a hexadecimal string. The third argument MAY be a number that represents the minimum number of characters to be present in the output.

The function calculates the number of bytes represented by the input hexadecimal string.

Character Count Note: The function throws an error if the first argument's value has an odd number of characters, as a valid hexadecimal number expressed in bytes must have an even number of characters. For example, 0x0F is the appropriate byte form expression of the decimal value 15.

For example, given the following Payload Template:

{
  "Parameters": {
    "SomeHex.$": "States.HexToByteCount('DEADBEEF')"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "SomeHex": 4
}

Another example, given the following Payload Template:

{
  "Parameters": {
    "SomeHex.$": "States.HexToByteCount('DEADBEEF', true)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "SomeHex": "04"
}

Another example, given the following Payload Template:

{
  "Parameters": {
    "SomeHex.$": "States.HexToByteCount('DEADBEEF', true, 8)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "SomeHex": "00000004"
}

States.Slice

This Intrinsic Function takes three arguments. The first argument's value MUST be a string. The second argument MUST be a number that represents the index (0-based) of the first character to include. The third argument MAY be a number that represents end index of where to stop including characters.

The resulting substring will include the characters up to, but not including, the character indicated by end. If this value is not specified, the substring continues to the end of original string.

For example, given the following Payload Template:

{
  "Parameters": {
    "someSubstring.$": "States.Slice('1F0025', 0, 1)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "someSubstring": "1"
}

Another example, given the following Payload Template:

{
  "Parameters": {
    "someSubstring.$": "States.Slice('1F0025', 3)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "someSubstring": "025"
}

States.SliceAndParseToNumber

This Intrinsic Function takes five arguments. The first argument's value MUST be a byte array where each value is expressed in hexadecimal format. The second argument MUST be a number that represents the index (0-based) of the first character to include. The third argument MUST be a number that represents the index of the last character to include. The fourth argument MAY be a boolean indicating whether the input byte array is represented in little-indian format. The fifth argument MAY be a boolean indicating that the input byte array is represented in signed 2's complement form.

The interpreter will return the parsed number.

This is useful when you are trying to extract information from the result of reading a memory location

For example, given the following Context and Payload Template:

Context
{
  "MPBID": [0x01,0x01,0x00,0x00,0x00]
}

{
  "Parameters": {
    "ProductId.$": "States.SliceAndParseToNumber($.MPBID, 0, 2)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "ProductId": 257
}

Another example, given the following Payload Template:

Context
{
  "Input": [0x01, 0x02, 0x03, 0x04]
}

{
  "Parameters": {
    "SomeParsedNumber.$": "States.SliceAndParseToNumber($.Input, 0, 2, true)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "SomeParsedNumber": 513
}

Another example, given the following Payload Template:

Context
{
  "Input": [0xA1, 0xA2, 0xA3, 0xA4]
}

{
  "Parameters": {
    "SomeParsedNumber.$": "States.SliceAndParseToNumber($.Input, 0, 1, false, true)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "SomeParsedNumber": -95
}

States.SliceAndParseToString

This Intrinsic Function takes three arguments. The first argument's value MUST be a byte array. The second argument MUST be a number that represents the index of the first character to include. The third argument MUST be a number that represents the index of the last character to include. The fourth argument MAY be a boolean indicating whether the input byte array is represented in little-indian format.

The interpreter will return the parsed hex string.

For example, given the following Context and Payload Template:

Context
{
  "MPBID": [1,1,0,0,0]
}

{
  "Parameters": {
    "ProductId.$": "States.SliceAndParseToString($.MPBID, 0, 2)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "ProductId": "0101"
}

Another example, given the following Payload Template:

Context
{
  "Input": [0x01, 0x02, 0x03, 0x04]
}

{
  "Parameters": {
    "SomeParsedString.$": "States.SliceAndParseToString($.Input, 0, 2, true)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "SomeParsedString": "0201"
}

States.SliceAndParseToDate

This Intrinsic Function takes three arguments. The first argument's value MUST be a byte array. The second argument MUST be a number that represents the index of the first character to include. The third argument MUST be a number that represents the index of the last character to include. The fourth argument MAY be a boolean indicating whether the input byte array is represented in little-indian format.

The interpreter will return the date representation of the byte array.

For example, given the following Context and Payload Template:

Context
{
  "Payload": [0x00, 0x62, 0xB3, 0x87, 0x1E, 0x00, 0x00, 0x00, 0x20, 0x20]
}

{
  "Type": "Pass",
  "Parameters": {
    "Date.$": "States.SliceAndParseToDate($.Payload, 1, 5)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "Date": "6/22/2022 4:18:22 PM"
}

Another example, given the following Payload Template:

Context
{
  "Payload": [0x00, 0x62, 0xB3, 0x87, 0x1E, 0x00, 0x00, 0x00, 0x20, 0x20]
}

{
  "Type": "Pass",
  "Parameters": {
    "Date.$": "States.SliceAndParseToDate($.Payload, 1, 5, true)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "Date": "3/26/1986 2:29:22 AM"
}

States.ByteArrayToNumber

This Intrinsic Function takes a first argument whose Value MUST be a number array and a second optional argument to denote if the array is in little endian. The interpreter will convert this array to a number.

This function is useful when you are trying to parse the response from a command

For example, given the following Context and Payload Template:

{
  "OpenLinkCommandResponse": {
    "Payload": [0, 0, 0, 10]
  }
}

{
  "Parameters": {
    "CycleCount.$": "States.ByteArrayToNumber($.OpenLinkCommandResponse.Payload, false)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "CycleCount": 10
}

States.ByteArrayToString

This Intrinsic Function takes a first argument whose Value MUST be a number array and a second optional argument to denote if the array is in little endian. The interpreter will convert this array to a string.

This function is useful when you are trying to parse the response from a command

For example, given the following Context and Payload Template:

{
  "OpenLinkCommandResponse": {
    "Payload": [0, 0, 0, 10]
  }
}

{
  "Parameters": {
    "CycleCount.$": "States.ByteArrayToString($.OpenLinkCommandResponse.Payload)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "CycleCount": "10"
}

States.ByteArrayToDate

This Intrinsic Function takes a first argument whose Value MUST be a number array and a second optional argument to denote if the array is in little endian. The interpreter will convert this array to a date.

This function is useful when you are trying to parse the response from a command

For example, given the following Context and Payload Template:

{
  "OpenLinkCommandResponse": {
    "Payload": [86, 134, 21, 224]
  }
}

{
  "Parameters": {
    "BornOnDate.$": "States.ByteArrayToDate($.OpenLinkCommandResponse.Payload)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "BornOnDate": "1/1/2016 12:00:00 AM"
}

States.ByteArrayToVersion

This Intrinsic Function takes a first argument whose Value MUST be a number array and a second optional argument to denote if the array is in little endian. The interpreter will convert this array to a version string.

This function is useful when you are trying to parse the response from a command

For example, given the following Context and Payload Template:

{
  "OpenLinkCommandResponse": {
    "Payload": [4, 1, 2, 3]
  }
}

{
  "Parameters": {
    "Version.$": "States.ByteArrayToVersion($.OpenLinkCommandResponse.Payload)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "Version": "4.1.2.3"
}

States.ByteArrayToMacAddress

This Intrinsic Function takes a single argument whose Value MUST be a decimal number array. The interpreter will convert this array to a MAC Address.

This function is useful when you are trying to parse the response from a command and using it connect over BLE

For example, given the following Context and Payload Template (note that the payload numbers are represented in decimal):

{
  "OpenLinkCommandResponse": {
    "Payload": [68, 80, 56, 20, 67, 12]
  }
}

{
  "Parameters": {
    "MACAddress.$": "States.ByteArrayToMacAddress($.OpenLinkCommandResponse.Payload)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "MACAddress": "44:50:38:14:43:0C"
}

States.ByteArrayToASCII

This Intrinsic Function takes a single argument whose Value MUST be a decimal number array. The interpreter will convert this array to the ASCII representation.

This function is useful when you are trying to parse the response from a command that stores it's values as number encoded ASCII

For example, given the following Context and Payload Template:

{
  "Result": [84, 69, 83, 84]
}

{
  "Parameters": {
    "ASCII.$": "States.ByteArrayToASCII($.Result)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "ASCII": "TEST"
}

States.ByteArrayToIEEE754

This Intrinsic Function takes a first argument whose Value MUST be a number array and a second optional argument to denote if the array is in little endian. The function is used to convert values to their float point representation using the IEEE754 conversion standard.

For example, given the following Context and Payload Template:

{
  "Value": [63,0,0,0]
}

{
  "Type": "Pass",
  "Parameters": {
    "Conversion.$": "States.ByteArrayToIEEE754($.Value)",
  }
}

After processing the Payload Template, the new payload becomes:

{
  "Conversion": 0.5,
}

States.AddNumbers

This Intrinsic Function takes a two arguments whose Values MUST be numeric. The interpreter will add the two numbers.

For example, given the following Context and Payload Template:

{
  "Value1": 1,
  "Value2": 2
}

{
  "Type": "Pass",
  "Parameters": {
    "Result.$": "States.AddNumbers($.Value1, $.Value2)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "Result": 3
}

States.RoundNumber

This Intrinsic Function takes two arguments. The first argument's value MUST be a number. The second argument MAY be a boolean indicating whether the number should be rounded up.

For example, given the following Context and Payload Template:

{
  "Payload": 8.2345

}

{
  "Type": "Pass",
  "Parameters": {
    "Result.$": "States.RoundNumber($.Payload)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "Result": 8
}

Another example, given the following Payload Template:

{
  "Payload": 8.2345
}

{
  "Type": "Pass",
  "Parameters": {
    "Result.$": "States.RoundNumber($.Payload, true)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "Result": 9
}

States.CalendarDateToUnixTime

This Intrinsic Function takes three arguments. All the arguments MUST be strings. The first argument is the year in the format YYYY, the second argument is the month in the format MM, and the third argument is the day in the format DD. The interpreter will convert the date to a Unix timestamp.

For example, given the following Context and Payload Template:

{
  "Type": "Pass",
  "Parameters": {
    "Result.$": "States.CalendarDateToUnixTime('2022', '06', '22')"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "Result": 1655874000
}

States.RemoveWhitespace

This Intrinsic Function takes a single argument whose Value MUST be a string. The interpreter will remove all whitespace characters from the string.

For example, given the following Context and Payload Template:

{
  "Type": "Pass",
  "Parameters": {
    "Result.$": "States.RemoveWhitespace('a b c d e f g')"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "Result": "abcdefg"
}

States.Includes

This Intrinsic Function is used to determine whether an array of values includes a particular value. It requires two arguments: the first being the array of values, and the second being the value of interest.

For example, given the following Context and Payload Template:

{
  "Values": [1, 2, 3, 4, 5],
  "MyValue": 2
}

{
  "Type": "Pass",
  "Parameters": {
    "Result.$": "States.Includes($.Values, $.MyValue)"
  }
}

After processing the Payload Template, the new payload becomes:

{
  "Result": true
}

States.IsBitSet

This Intrinsic Function is used to determine whether bit is set high on a particular value. It requires two arguments: the first being the bit position, and the second being the value of interest to check against.

For example, given the following Context and Payload Template:

{
  "Value": 14
}

{
  "Type": "Pass",
  "Parameters": {
    "FirstBit.$": "States.IsBitSet(0, $.Value)",
    "SecondBit.$": "States.IsBitSet(1, $.Value)",
    "ThirdBit.$": "States.IsBitSet(2, $.Value)",
    "FourthBit.$": "States.IsBitSet(3, $.Value)",
  }
}

After processing the Payload Template, the new payload becomes:

{
  "FirstBit": true,
  "SecondBit": false,
  "ThirdBit": false,
  "FourthBit": false,
}

States.Equation

This Intrinsic Function takes one or more arguments. The Value of the first MUST be a string, which MAY include zero or more instances of the character sequence {}. There MUST be as many remaining arguments in the Intrinsic Function as there are occurrences of {}. The interpreter evaluates the first argument as the equation with each {} replaced by the Value of the positionally-corresponding argument in the Intrinsic Function.

For example, given the following Context and Payload Template:

{
  "Type": "Pass",
  "Parameters": {
    "Result.$": "States.Equation('Math.abs((({} / 100 - {})/{}) * 100)', '06', '22', $.SomeVariable)"
  }
}

See Math Documentation for list of available functions.